home *** CD-ROM | disk | FTP | other *** search
/ Amiga Tools 4 / Amiga Tools 4.iso / tools / internet-tools / connect-line / cl / devkit / docs / clutil.doc < prev    next >
Encoding:
Text File  |  1995-09-01  |  29.8 KB  |  1,350 lines
  1. TABLE OF CONTENTS
  2.  
  3. clutil.library/--background--
  4. clutil.library/CLU_Alert
  5. clutil.library/CLU_AllocVMem
  6. clutil.library/CLU_clnl
  7. clutil.library/CLU_CloseTempFile
  8. clutil.library/CLU_CreateProc
  9. clutil.library/CLU_ELSwapNodes
  10. clutil.library/CLU_FreeFilelist
  11. clutil.library/CLU_FreeVMem
  12. clutil.library/CLU_MakeFilelist
  13. clutil.library/CLU_MUI_InsertSingleStringA
  14. clutil.library/CLU_MUI_RunCommandA
  15. clutil.library/CLU_MUI_SetTextA
  16. clutil.library/CLU_NOL_AddEntry
  17. clutil.library/CLU_NOL_ChangeCounter
  18. clutil.library/CLU_NOL_Clone
  19. clutil.library/CLU_NOL_Delete
  20. clutil.library/CLU_NOL_DeleteEntry
  21. clutil.library/CLU_NOL_FindEntry
  22. clutil.library/CLU_NOL_GetEntry
  23. clutil.library/CLU_NOL_GetEntryData
  24. clutil.library/CLU_NOL_GetEntryName
  25. clutil.library/CLU_NOL_GetFirstEntry
  26. clutil.library/CLU_NOL_GetLastEntry
  27. clutil.library/CLU_NOL_GetNextEntry
  28. clutil.library/CLU_NOL_GetNumEntries
  29. clutil.library/CLU_NOL_GetPrevEntry
  30. clutil.library/CLU_NOL_Info
  31. clutil.library/CLU_NOL_Lock
  32. clutil.library/CLU_NOL_NewA
  33. clutil.library/CLU_NOL_SetEntryName
  34. clutil.library/CLU_NOL_SwapEntries
  35. clutil.library/CLU_NOL_UnLock
  36. clutil.library/CLU_OpenLibraryCode
  37. clutil.library/CLU_OpenTempFile
  38. clutil.library/CLU_ScanDir
  39. clutil.library/CLU_SkipDot
  40. clutil.library/--background--                   clutil.library/--background--
  41.  
  42.  OVERVIEW
  43.  
  44.  The "clutil.library" provides all kinds of low level functions for
  45.  the Connectline system. The Library itself does not depend on any other
  46.  Connectline module. Besides functions to overcome several 2.x quirks
  47.  it provides a extended version of the well known AsyncIO routines,
  48.  several general utility functions dealing with AmigaDOS, support
  49.  for private named semaphores and a general data storage abstraction
  50.  called "Named Object Lists" or NOLs. The NOL facility is used by
  51.  the "cl_prefs.library" to store complex data structures.
  52.  
  53.  All "clutil.library" calls are implemented with respect for maximum
  54.  efficiency. You should *never* use your own routines if something
  55.  similiar is already provided in "clutil.library".
  56.  
  57.  There is a SAS/C link library called "cl.lib" which provides the
  58.  link interface to several parts of the clutil.library functionality.
  59.  
  60. clutil.library/CLU_Alert                             clutil.library/CLU_Alert
  61.  
  62.    NAME
  63.    CLU_Alert -- Connectline specific Alert() with logging (V35)
  64.  
  65.    SYNOPSIS
  66.    CLU_Alert( subsysid, specific )
  67.               D0        D1
  68.                      
  69.  
  70.    void CLU_Alert( UBYTE, UWORD );
  71.  
  72.    FUNCTION
  73.    Output connectline specific alert code with exec.library/Alert()
  74.    and store log entry in "CONNECTLINE:Alert.Log".
  75.  
  76.    INPUTS
  77.    subsysid
  78.    specific -- see include file cl/clalerts.h for definitions.
  79.  
  80.    RESULT
  81.    None. 
  82.  
  83.    EXAMPLE
  84.  
  85.    NOTES
  86.    If opening of the Alert.Log succeeds, this function will delay
  87.    the Alert() about 1 second to allow the filesystem to settle
  88.    down. 
  89.    
  90.    BUGS
  91.    None known.
  92.  
  93.    SEE ALSO
  94.  
  95. clutil.library/CLU_AllocVMem                     clutil.library/CLU_AllocVMem
  96.  
  97.    NAME
  98.    CLU_AllocVMem -- allocate (possibly virtual) memory (V31)
  99.  
  100.    SYNOPSIS
  101.    memblock = CLU_AllocVMem( size, flags )
  102.    D0                        D0    D1
  103.                      
  104.  
  105.    APTR CLU_AllocVMem( ULONG, ULONG );
  106.  
  107.    FUNCTION
  108.    Allocate memory, possibly virtual.
  109.  
  110.    INPUTS
  111.    size -- size of memory block to allocate.
  112.    flags -- allowed flags are:
  113.  
  114.             MEMF_CLEAR
  115.             MEMF_PROTECT
  116.  
  117.  
  118.    RESULT
  119.    memblock -- pointer to memory block or NULL.
  120.  
  121.    EXAMPLE
  122.  
  123.    NOTES
  124.    You can also use MEMF_CLEAR and MEMF_PROTECT in conjunction
  125.    with CLU_CreatePool().
  126.  
  127.    BUGS
  128.    None known.
  129.  
  130.    SEE ALSO
  131.    clutil.library/CLU_FreeVMem, clutil.library/CLU_CreatePool
  132.  
  133. clutil.library/CLU_clnl                               clutil.library/CLU_clnl
  134.  
  135.    NAME
  136.    CLU_clnl -- clear CR/LF at end of line.
  137.  
  138.    SYNOPSIS
  139.    CLU_clnl( string )
  140.              A0
  141.  
  142.    FUNCTION
  143.    Clears any CR or LF characters at the end of the string.
  144.  
  145.    INPUTS
  146.    string -- pointer to string (contents will be modified!)
  147.  
  148.    RESULT
  149.    None.
  150.  
  151.    EXAMPLE
  152.  
  153.    NOTES
  154.  
  155.    BUGS
  156.    None known.
  157.  
  158.    SEE ALSO
  159.  
  160. clutil.library/CLU_CloseTempFile             clutil.library/CLU_CloseTempFile
  161.  
  162.    NAME
  163.    CLU_CloseTempFile -- close and delete a temporary file (V27)
  164.  
  165.    SYNOPSIS
  166.    CLU_CloseTempFile( tempfile, delete )
  167.                       A0        d0
  168.  
  169.    void CLU_CloseTempFile( BPTR, BOOL );
  170.  
  171.    FUNCTION
  172.    Closes and optionally deletes a temporary file
  173.    created by CLU_OpenTempFile().
  174.  
  175.    INPUTS
  176.    tempfile -- AmigaDOS filehandle as returned by CLU_OpenTempFile().
  177.  
  178.    delete -- flag; TRUE deletes file after closing.
  179.  
  180.    RESULT
  181.    None.
  182.  
  183.    EXAMPLE
  184.  
  185.    NOTES
  186.  
  187.    BUGS
  188.    None known.
  189.  
  190.    SEE ALSO
  191.    CLU_OpenTempFile()
  192.  
  193. clutil.library/CLU_CreateProc                   clutil.library/CLU_CreateProc
  194.  
  195.    NAME
  196.    CLU_CreateProc -- create process with register setup (V50)
  197.    CLU_CreateProcTags -- varargs version
  198.  
  199.    SYNOPSIS
  200.    process = CLU_CreateProc( entry, registerinfo, tags )
  201.    D0                         A0       A1          A2
  202.  
  203.    struct Process * CLU_CreateProc( FUNCPTR entry, 
  204.                      struct CLU_RegisterInfo *reginfo,
  205.                      struct TagItem *tags );
  206.    struct Process * CLU_CreateProcTags( FUNCPTR entry, 
  207.                      struct CLU_RegisterInfo *reginfo,
  208.                      ... );
  209.  
  210.    FUNCTION
  211.    Calls dos.library/CreateNewProc() to create a new process
  212.    as specified by "tags". Before entering the given entrypoint,
  213.    registers are set up according to registerinfo. This allows
  214.    specifying arguments and/or base pointers.
  215.  
  216.    INPUTS
  217.    entry -- entry point to call.
  218.    registerinfo -- pointer to struct CLU_RegisterInfo
  219.    tags -- tags passed to CreateNewProcTags()
  220.  
  221.    RESULT
  222.    process -- pointer to process or NULL upon failure.
  223.  
  224.    EXAMPLE
  225.  
  226.    NOTES
  227.    Note that you may not setup registers A2 and A3 because
  228.    they are required for setting up the new process.
  229.  
  230.    BUGS
  231.    None known.
  232.  
  233.    SEE ALSO
  234.    dos.library/CreateNewProc()
  235.  
  236. clutil.library/CLU_ELSwapNodes                 clutil.library/CLU_ELSwapNodes
  237.  
  238.    NAME
  239.    CLU_ELSwapNodes -- swap to exec list nodes
  240.  
  241.    SYNOPSIS
  242.    CLU_ELSwapNodes( node1, node2 )
  243.                     A0     A1
  244.  
  245.    void CLU_ELSwapNodes( struct Node *, struct Node * );
  246.  
  247.    FUNCTION
  248.    Exchanges the two nodes on the exec list.
  249.  
  250.    INPUTS
  251.    node1
  252.    node2 -- pointer standard exec MinNodes or extensions.
  253.  
  254.    RESULT
  255.    None.
  256.  
  257.    EXAMPLE
  258.  
  259.    NOTES
  260.    Make sure both node pointer are valid and on the same
  261.    list, otherwise this function will cause unpredictable
  262.    results.
  263.  
  264.    This function does not require A6 to be set up.
  265.  
  266.    BUGS
  267.  
  268.    SEE ALSO
  269.  
  270. clutil.library/CLU_FreeFilelist               clutil.library/CLU_FreeFilelist
  271.  
  272.    NAME
  273.    CLU_FreeFileList -- free file list (V29)
  274.  
  275.    SYNOPSIS
  276.    CLU_FreeFileList( filelist )
  277.                      A0         
  278.  
  279.    void CLU_FreeFileList( struct clu_filelist * );
  280.  
  281.    FUNCTION
  282.    Free a file list obtained via CLU_MakeFileList().
  283.  
  284.    INPUTS
  285.    filelist -- pointer to clu_filelist as returned by CLU_MakeFileList().
  286.  
  287.    RESULT
  288.    None.
  289.  
  290.    EXAMPLE
  291.  
  292.    NOTES
  293.  
  294.    BUGS
  295.    None known.
  296.  
  297.    SEE ALSO
  298.    CLU_MakeFilelist(), CLU_ScanDir()
  299.  
  300. clutil.library/CLU_FreeVMem                       clutil.library/CLU_FreeVMem
  301.  
  302.    NAME
  303.    CLU_FreeVMem -- free memory allocated by CLU_AllocVMem (V31)
  304.  
  305.    SYNOPSIS
  306.    CLU_FreeVMem( memblock )
  307.                  A0
  308.                      
  309.  
  310.    void CLU_FreeVMem( APTR );
  311.  
  312.    FUNCTION
  313.    Free memory allocated via CLU_AllocVMem()
  314.  
  315.    INPUTS
  316.    memblock -- pointer to memory block as returnd by CLU_AllocVMem().
  317.  
  318.    RESULT
  319.    None.
  320.  
  321.    EXAMPLE
  322.  
  323.    NOTES
  324.    Unlike other OS memory function, this call silently accepts
  325.    a NULL pointer.
  326.  
  327.    BUGS
  328.    None known.
  329.  
  330.    SEE ALSO
  331.    clutil.library/CLU_AllocVMem, clutil.library/CLU_CreatePool
  332.  
  333. clutil.library/CLU_MakeFilelist               clutil.library/CLU_MakeFilelist
  334.  
  335.    NAME
  336.    CLU_MakeFileList -- scan a directory and return link list of FIBs (V29)
  337.  
  338.    SYNOPSIS
  339.    filelist = CLU_MakeFileList( dirlock, pattern, flags )
  340.    D0                           A0       A1       D0
  341.  
  342.    struct clu_filelist * CLU_MakeFileList( BPTR, STRPTR, ULONG );
  343.  
  344.    FUNCTION
  345.    Scans the given directory and returns a link list of
  346.    file info blocks.
  347.  
  348.    INPUTS
  349.    dirlock -- AmigaDOS lock on directory to examine.
  350.  
  351.    pattern -- optional match pattern or NULL.
  352.  
  353.    flags -- possible flags:
  354.  
  355.               CLUMFLF_NODIRS    filter directories
  356.               CLUMFLF_NOFILES   filter files
  357.               CLUMFLF_NOINFOS   filter icon files
  358.               CLUMFLF_SORT         sort entries (V46)
  359.  
  360.    RESULT
  361.    filelist -- pointer to a struct clu_filelist. You *MUST*
  362.                free this via CLU_FreeFileList(). NULL upon
  363.                error, see IoErr() for more information.
  364.  
  365.    EXAMPLE
  366.  
  367.    NOTES
  368.  
  369.    BUGS
  370.    None known.
  371.  
  372.    SEE ALSO
  373.    CLU_FreeFilelist(), CLU_ScanDir()
  374.  
  375. clutil.library/CLU_MUI_InsertSingleStringAlibrary/CLU_MUI_InsertSingleStringA
  376.  
  377.    NAME
  378.    CLU_MUI_InsertSingleStringA -- perform MUIM_List_InsertSingle with
  379.                                   printf()-like formating (V31)
  380.    CLU_MUI_InsertSingleString -- varargs version
  381.  
  382.    SYNOPSIS
  383.    CLU_MUI_InsertSingleStringA( listobj, pos, fmt, data )
  384.                                 A0       D0   A1   A2 
  385.  
  386.    void CLU_MUI_InsertSingleStringA( APTR, STRPTR, APTR );
  387.    void CLU_MUI_InsertSingleString( APTR, STRPTR, ... );
  388.  
  389.    FUNCTION
  390.    Perform MUIM_List_InsertSingle on a standard MUI string
  391.    list with formating.
  392.  
  393.    INPUTS
  394.    listobj -- MUI list object.
  395.    pos -- position to add string.
  396.    fmt -- standard printf()-like formating string
  397.    data -- optional arguments (denoted by fmt)
  398.  
  399.    RESULT
  400.    None.
  401.  
  402.    EXAMPLE
  403.  
  404.    NOTES
  405.  
  406.    BUGS
  407.    None known.
  408.  
  409.    SEE ALSO
  410.    exec.library/RawDoFmt()
  411.  
  412. clutil.library/CLU_MUI_RunCommandA         clutil.library/CLU_MUI_RunCommandA
  413.  
  414.    NAME
  415.    CLU_MUI_RunCommandA -- execute shell program while performing
  416.                           MUIM_Application_InputBuffered (V32)
  417.                           
  418.    CLU_MUI_RunCommand -- varargs version
  419.  
  420.    SYNOPSIS
  421.    rc = CLU_MUI_RunCommandA( appobj, cmd, tags )
  422.    D0                        A0      A1   A3
  423.  
  424.    void CLU_MUI_RunCommandA( APTR, STRPTR, APTR );
  425.    void CLU_MUI_RunCommand( APTR, STRPTR, ... );
  426.  
  427.    FUNCTION
  428.    Execute the given shell program while performing
  429.    MUIM_Application_InputBuffered. This allows for application
  430.    windows to be still operatable while the application is
  431.    executing a shell command.
  432.  
  433.    INPUTS
  434.    appobj -- MUI application object to perform 
  435.              MUIM_Application_InputBuffered on.
  436.    path   -- full commandline of program to execute.
  437.    tags -- optional Tags passed down to CreateNewProc().
  438.  
  439.    RESULT
  440.    rc -- return code from command or -1 upon error.
  441.          Use dos.library/IoErr() to obtain the secondary
  442.          result code.
  443.  
  444.    EXAMPLE
  445.  
  446.    NOTES
  447.    This function actually creates a secondary process
  448.    via CreateNewProc()  and has this process run the
  449.    requested command via SystemTagList(). Your tags
  450.    affect the initial CreateNewProc(), not the
  451.    SystemTagList(), which inherits it's parameters
  452.    from the parent process as stated in dos.doc.
  453.  
  454.    Several tags are filtered by this function before
  455.    they are passed down to CreateNewProc(). As of
  456.    V33, this filtering includes:
  457.         NP_ExitCode
  458.         NP_ExitData
  459.         NP_Entry
  460.         NP_Seglist
  461.         NP_FreeSeglist
  462.         NP_Arguments
  463.         NP_Cli
  464.         NP_CommandName
  465.  
  466.    BUGS
  467.    Not functional until V33.
  468.  
  469.    SEE ALSO
  470.    dos.library/CreateNewProc(), dos.library/SystemTagList()
  471.  
  472. clutil.library/CLU_MUI_SetTextA               clutil.library/CLU_MUI_SetTextA
  473.  
  474.    NAME
  475.    CLU_MUI_SetTextA -- set MUI text gadget with %-formatting (V30)
  476.    CLU_MUI_SetText -- varargs version
  477.  
  478.    SYNOPSIS
  479.    CLU_MUI_SetTextA( textobj, fmt, data )
  480.                      A0       A1   A2 
  481.  
  482.    void CLU_MUI_SetTextA( APTR, STRPTR, APTR );
  483.    void CLU_MUI_SetText( APTR, STRPTR, ... );
  484.  
  485.    FUNCTION
  486.    Sets the contents of a MUI text gadget via RawDoFmt().
  487.  
  488.    INPUTS
  489.    textobj -- MUI text object
  490.    fmt -- standard printf()-like formating string
  491.    data -- optional arguments (denoted by fmt)
  492.  
  493.    RESULT
  494.    None.
  495.  
  496.    EXAMPLE
  497.  
  498.    NOTES
  499.  
  500.    BUGS
  501.    None known.
  502.  
  503.    SEE ALSO
  504.    exec.library/RawDoFmt()
  505.  
  506. clutil.library/CLU_NOL_AddEntry               clutil.library/CLU_NOL_AddEntry
  507.  
  508.    NAME
  509.    CLU_NOL_AddEntry -- Add an entry to a NOL.
  510.  
  511.    SYNOPSIS
  512.    nobjhandle =
  513.     CLU_NOL_AddEntry( nolhandle, objname, objdata, insertmode [, refobj ] )
  514.    D0                 A0         A1       A2       D0            A3
  515.  
  516.    NOBJ CLU_NOL_AddEntry( NOL, STRPTR, APTR, ULONG, NOBJ );
  517.  
  518.    FUNCTION
  519.    Add an entry to the specified NOL. The data is copied
  520.    to the private NOL memory and can be freed after this call.
  521.    If an object with the same name already exists, this
  522.    function will return NULL and set IoErr() to
  523.    ERROR_OBJECT_EXISTS, unless the NOLIMF_OVERWRITE is set.
  524.  
  525.    INPUTS
  526.    nolhandle -- as returned by by CLU_NOL_New() et al.
  527.    objname -- name of object to add.
  528.    objdata -- data ob object, only necessary if NOLT_ENTRYSIZE
  529.               was used on CLU_NOL_New()
  530.    insertmode -- one of:
  531.           NOLIM_ADDHEAD -- add to head of list
  532.           NOLIM_ADDTAIL -- add to tail of list
  533.           NOLIM_INSERT_BEFORE -- insert before refobj
  534.           NOLIM_INSERT_AFTER  -- insert after refobj
  535.           NOLIM_INSERT_SORTED -- insert sorted (NYI)
  536.  
  537.           Also, NOLIMF_OVERWRITE may be set to force
  538.           overwrite of an existing object.
  539.  
  540.    refobj -- reference NOBJ for NOLIM_INSERT_BEFORE or
  541.              NOLIM_INSERT_AFTER.
  542.  
  543.  
  544.    RESULT
  545.    nobjhandle -- private pointer to the new object or NULL upon failure.
  546.                  IoErr() will hold ERROR_OBJECT_EXISTS or 
  547.                  ERROR_NO_FREE_STORE to show what's going on.
  548.  
  549.    EXAMPLE
  550.        APTR nolhandle;
  551.        APTR nobjhandle;
  552.        struct mydata mydata;
  553.        nobjhandle = CLU_NOL_AddEntry( nolhandle, "Guest", &mydata,
  554.            NOLIM_HEAD );
  555.  
  556.    NOTES
  557.  
  558.    BUGS
  559.    none known
  560.  
  561.    SEE ALSO
  562.  
  563. clutil.library/CLU_NOL_ChangeCounter     clutil.library/CLU_NOL_ChangeCounter
  564.  
  565.    NAME
  566.    CLU_NOL_ChangeCounter -- Get change counter of a NOL (V35).
  567.  
  568.    SYNOPSIS
  569.    count = CLU_NOL_ChangeCounter( nol, reset )
  570.    D0                             A0   D0
  571.  
  572.    ULONG CLU_NOL_ChangeCounter( NOL, BOOL );
  573.  
  574.    FUNCTION
  575.    Returns the change counter of the NOL. If reset is TRUE, also
  576.    resets this to Zero.
  577.  
  578.    INPUTS
  579.    nolhandle -- standard nol handle.
  580.    reset -- flag, resets counter to Zero if TRUE
  581.  
  582.    RESULT
  583.    count -- current change counter.
  584.  
  585.    EXAMPLE
  586.  
  587.    NOTES
  588.    Passing a NULL pointer will be penalted by a NULL return.
  589.  
  590.    BUGS
  591.    None known.
  592.  
  593.    SEE ALSO
  594.  
  595. clutil.library/CLU_NOL_Clone                     clutil.library/CLU_NOL_Clone
  596.  
  597.    NAME
  598.    CLU_NOL_Clone -- Clone a NOL and all it's entries.
  599.  
  600.    SYNOPSIS
  601.    newnol = CLU_NOL_Clone( nolhandle )
  602.    D0                      A0
  603.  
  604.    void * CLU_NOL_Clone( void * );
  605.  
  606.    FUNCTION
  607.    Clones the specified NOL and returns a nolhandle to the
  608.    new list. All entries in the source NOL are duplicated. 
  609.  
  610.    INPUTS
  611.    nolhandle -- as returned by by CLU_NOL_New() et al.
  612.  
  613.    RESULT
  614.    newnol -- nolhandle to cloned NOL.
  615.  
  616.    EXAMPLE
  617.  
  618.    NOTES
  619.    Passing a NULL pointer will be penalted by a NULL return.
  620.  
  621.    BUGS
  622.    none known
  623.  
  624.    SEE ALSO
  625.  
  626. clutil.library/CLU_NOL_Delete                   clutil.library/CLU_NOL_Delete
  627.  
  628.    NAME
  629.    CLU_NOL_Delete -- Delete a Named Object List. (V24)
  630.  
  631.    SYNOPSIS
  632.    CLU_NOL_Delete( nolhandle )
  633.                    A0
  634.  
  635.    void CLU_NOL_Delete( void * );
  636.  
  637.    FUNCTION
  638.    Delete the specified NOL and all it's entries.
  639.  
  640.    INPUTS
  641.    nolhandle -- as returned by by CLU_NOL_New() et al.
  642.  
  643.    RESULT
  644.    none
  645.  
  646.    EXAMPLE
  647.        APTR nolhandle;
  648.        CLU_NOL_Delete( nolhandle );
  649.  
  650.    NOTES
  651.    A NULL pointer is silently accepted for easy cleanup
  652.    procedures.
  653.  
  654.    BUGS
  655.    none known
  656.  
  657.    SEE ALSO
  658.  
  659. clutil.library/CLU_NOL_DeleteEntry         clutil.library/CLU_NOL_DeleteEntry
  660.  
  661.    NAME
  662.    CLU_NOL_DeleteEntry -- Delete a NOL entry. (V24)
  663.  
  664.    SYNOPSIS
  665.    CLU_NOL_DeleteEntry( nobjhandle )
  666.                         A0
  667.  
  668.    void CLU_NOL_DeleteEntry( void * );
  669.  
  670.    FUNCTION
  671.    Delete the specified NOL entry.
  672.  
  673.    INPUTS
  674.    nobjhandle -- a named object handle.
  675.  
  676.    RESULT
  677.    none
  678.  
  679.    EXAMPLE
  680.        APTR nobjhandle;
  681.        CLU_NOL_DeleteEntry( nobjhandle );
  682.  
  683.    NOTES
  684.    A NULL pointer is silently accepted for easy cleanup
  685.    procedures.
  686.  
  687.    BUGS
  688.    none known
  689.  
  690.    SEE ALSO
  691.  
  692. clutil.library/CLU_NOL_FindEntry             clutil.library/CLU_NOL_FindEntry
  693.  
  694.    NAME
  695.    CLU_NOL_FindEntry -- Find an entry in a NOL by name.
  696.  
  697.    SYNOPSIS
  698.    nobjhandle = CLU_NOL_FindEntry( nolhandle, objname )
  699.    D0                              A0         A1
  700.  
  701.    void CLU_NOL_FindEntry( void *, STRPTR );
  702.  
  703.    FUNCTION
  704.    Search the specified NOL for object "objname" and return
  705.    a private pointer to it (nobjhandle).
  706.  
  707.    INPUTS
  708.    nolhandle -- as returned by by CLU_NOL_New() et al.
  709.    objname -- name of object to look for
  710.  
  711.    RESULT
  712.    nobjhandle -- private pointer to object or NULL upon failure.
  713.  
  714.    EXAMPLE
  715.        APTR nolhandle;
  716.        APTR nobjhandle;
  717.        nobjhandle = CLU_NOL_FindEntry( nolhandle, "Guest" );
  718.  
  719.    NOTES
  720.  
  721.    BUGS
  722.    none known
  723.  
  724.    SEE ALSO
  725.  
  726. clutil.library/CLU_NOL_GetEntry               clutil.library/CLU_NOL_GetEntry
  727.  
  728.    NAME
  729.    CLU_NOL_GetEntry -- Get NOL entry by index (V41)
  730.  
  731.    SYNOPSIS
  732.    NOBJ = CLU_NOL_GetEntry( nolhandle, index )
  733.    D0                           A0       D0
  734.  
  735.    void * CLU_NOL_GetEntry( void *, ULONG index );
  736.  
  737.    FUNCTION
  738.    
  739.  
  740.    INPUTS
  741.    nolhandle -- named object list.
  742.    index -- integral index into list.
  743.  
  744.    RESULT
  745.    nobj -- nobjhandle to indexed object or NULL
  746.  
  747.    EXAMPLE
  748.  
  749.    NOTES
  750.    Passing a NULL pointer will be penalted by a NULL return.
  751.  
  752.    BUGS
  753.    none known
  754.  
  755.    SEE ALSO
  756.  
  757. clutil.library/CLU_NOL_GetEntryData       clutil.library/CLU_NOL_GetEntryData
  758.  
  759.    NAME
  760.    CLU_NOL_GetEntryData -- Get pointer to data of a nobjhandle
  761.  
  762.    SYNOPSIS
  763.    data = CLU_NOL_GetEntryData( nobjhandle )
  764.    D0                           A0
  765.  
  766.    void * CLU_NOL_GetEntryData( void * );
  767.  
  768.    FUNCTION
  769.    Returns the name of the specified named object.
  770.  
  771.    INPUTS
  772.    nobjhandle -- as returned by by CLU_NOL_FindEntry() et al.
  773.  
  774.    RESULT
  775.    name -- APTR to entry data. DON'T TOUCH THIS!
  776.  
  777.    EXAMPLE
  778.        APTR nobjhandle;
  779.        struct mydata * mydata;
  780.        mydata = CLU_NOL_GetEntryData( nobjhandle );
  781.        Printf( "mydata->taler = %ld\n", mydata->taler );
  782.  
  783.    NOTES
  784.  
  785.    BUGS
  786.    none known
  787.  
  788.    SEE ALSO
  789.  
  790. clutil.library/CLU_NOL_GetEntryName       clutil.library/CLU_NOL_GetEntryName
  791.  
  792.    NAME
  793.    CLU_NOL_GetEntryName -- Get name of a nobjhandle
  794.  
  795.    SYNOPSIS
  796.    name = CLU_NOL_GetEntryName( nobjhandle )
  797.    D0                           A0
  798.  
  799.    STRPTR CLU_NOL_GetEntryName( void * );
  800.  
  801.    FUNCTION
  802.    Returns the name of the specified named object.
  803.  
  804.    INPUTS
  805.    nobjhandle -- as returned by by CLU_NOL_FindEntry() et al.
  806.  
  807.    RESULT
  808.    name -- STRPTR to entry name. DON'T CHANGE THIS!
  809.  
  810.    EXAMPLE
  811.        APTR nobjhandle;
  812.        STRPTR name;
  813.        name = CLU_NOL_GetEntryName( nobjhandle );
  814.        Printf( "name = %s\n", name );
  815.  
  816.    NOTES
  817.  
  818.    BUGS
  819.    none known
  820.  
  821.    SEE ALSO
  822.  
  823. clutil.library/CLU_NOL_GetFirstEntry     clutil.library/CLU_NOL_GetFirstEntry
  824.  
  825.    NAME
  826.    CLU_NOL_GetFirstEntry -- Get first entry of a NOL (V35).
  827.  
  828.    SYNOPSIS
  829.    nobj = CLU_NOL_GetFirstEntry( nol )
  830.    D0                            A0
  831.  
  832.    NOBJ CLU_NOL_GetFirstEntry( NOL );
  833.  
  834.    FUNCTION
  835.    Returns the first entry in the NOL or NULL if the NOL is
  836.    empty.
  837.  
  838.    INPUTS
  839.    nolhandle -- standard nol handle.
  840.  
  841.    RESULT
  842.    nextnobj -- nobjhandle to first object or NULL.
  843.  
  844.    EXAMPLE
  845.  
  846.    NOTES
  847.  
  848.    BUGS
  849.    None known.
  850.  
  851.    SEE ALSO
  852.    CLU_NOL_GetLastEntry()
  853.  
  854. clutil.library/CLU_NOL_GetLastEntry       clutil.library/CLU_NOL_GetLastEntry
  855.  
  856.    NAME
  857.    CLU_NOL_GetLastEntry -- Get last entry of a NOL (V35).
  858.  
  859.    SYNOPSIS
  860.    nobj = CLU_NOL_GetLastEntry( nol )
  861.    D0                           A0
  862.  
  863.    NOBJ CLU_NOL_GetLastEntry( NOL );
  864.  
  865.    FUNCTION
  866.    Returns the last entry in the NOL or NULL if the NOL is
  867.    empty.
  868.  
  869.    INPUTS
  870.    nolhandle -- standard nol handle.
  871.  
  872.    RESULT
  873.    nextnobj -- nobjhandle to last object or NULL.
  874.  
  875.    EXAMPLE
  876.  
  877.    NOTES
  878.  
  879.    BUGS
  880.    None known.
  881.  
  882.    SEE ALSO
  883.    CLU_NOL_GetFirstEntry()
  884.  
  885. clutil.library/CLU_NOL_GetNextEntry       clutil.library/CLU_NOL_GetNextEntry
  886.  
  887.    NAME
  888.    CLU_NOL_GetNextEntry -- Get next entry in NOL.
  889.  
  890.    SYNOPSIS
  891.    nextnobj = CLU_NOL_GetNextEntry( nobjhandle )
  892.    D0                               A0
  893.  
  894.    void * CLU_NOL_GetNextEntry( void * );
  895.  
  896.    FUNCTION
  897.    Returns the next entry in the NOL following the specified
  898.    entry or NULL if end of list.
  899.  
  900.    INPUTS
  901.    nobjhandle -- as returned by by CLU_NOL_FindEntry() et al.
  902.  
  903.    RESULT
  904.    nextnobj -- nobjhandle to next object or NULL
  905.  
  906.    EXAMPLE
  907.  
  908.    NOTES
  909.    Passing a NULL pointer will be penalted by a NULL return.
  910.  
  911.    BUGS
  912.    none known
  913.  
  914.    SEE ALSO
  915.  
  916. clutil.library/CLU_NOL_GetNumEntries     clutil.library/CLU_NOL_GetNumEntries
  917.  
  918.    NAME
  919.    CLU_NOL_GetNumEntries -- Get number of entries in a NOL.
  920.  
  921.    SYNOPSIS
  922.    num = CLU_NOL_GetNumEntries( nolhandle )
  923.    D0                           A0
  924.  
  925.    LONG CLU_NOL_GetNumEntries( void * );
  926.  
  927.    FUNCTION
  928.    Returns the number of entries in the specified NOL.
  929.  
  930.    INPUTS
  931.    nolhandle -- as returned by by CLU_NOL_New() et al.
  932.  
  933.    RESULT
  934.    num -- number of entries.
  935.  
  936.    EXAMPLE
  937.  
  938.    NOTES
  939.    Passing a NULL pointer will yield a result of -1. 
  940.  
  941.    BUGS
  942.    none known
  943.  
  944.    SEE ALSO
  945.  
  946. clutil.library/CLU_NOL_GetPrevEntry       clutil.library/CLU_NOL_GetPrevEntry
  947.  
  948.    NAME
  949.    CLU_NOL_GetPrevEntry -- Get previous entry in NOL.
  950.  
  951.    SYNOPSIS
  952.    prevnobj = CLU_NOL_GetPrevEntry( nobjhandle )
  953.    D0                               A0
  954.  
  955.    void * CLU_NOL_GetPrevEntry( void * );
  956.  
  957.    FUNCTION
  958.    Returns the previous entry in the NOL before the specified
  959.    entry or NULL if end of list.
  960.  
  961.    INPUTS
  962.    nobjhandle -- as returned by by CLU_NOL_FindEntry() et al.
  963.  
  964.    RESULT
  965.    prevnobj -- nobjhandle to previous object or NULL
  966.  
  967.    EXAMPLE
  968.  
  969.    NOTES
  970.    Passing a NULL pointer will be penalted by a NULL return.
  971.  
  972.    BUGS
  973.    none known
  974.  
  975.    SEE ALSO
  976.  
  977. clutil.library/CLU_NOL_Info                       clutil.library/CLU_NOL_Info
  978.  
  979.    NAME
  980.    CLU_NOL_Info -- Return information about a NOL. (V24)
  981.  
  982.    SYNOPSIS
  983.    infoversion = CLU_NOL_Info( nolhandle, nolinfo )
  984.    D0                          A0         A1
  985.  
  986.    ULONG CLU_NOL_Info( APTR, struct NOL_Info * );
  987.  
  988.    FUNCTION
  989.    Return information about the specified NOL.
  990.  
  991.    The NOL_Info structure is defined as:
  992.  
  993.      struct NOL_Info {
  994.        ULONG nol_info_version;    /* set to NOL_INFO_VERSION */
  995.        ULONG nol_entrysize;    /* per entry size */
  996.        ULONG nol_num_entries;    /* number of entries */
  997.      };
  998.  
  999.  
  1000.    INPUTS
  1001.    nolhandle -- private NOL handle.
  1002.    nolinfo -- Pointer to a structure of type NOL_Info.
  1003.  
  1004.    RESULT
  1005.    infoversion -- equal to NOL_INFO_VERSION or 0 if an
  1006.                   error occured.
  1007.  
  1008.    EXAMPLE
  1009.        APTR nolhandle;
  1010.        struct NOL_Info nolinfo;
  1011.        CLU_NOL_INFO( nolhandle, &nolinfo );
  1012.  
  1013.    NOTES
  1014.  
  1015.    BUGS
  1016.    none known
  1017.  
  1018.    SEE ALSO
  1019.  
  1020. clutil.library/CLU_NOL_Lock                       clutil.library/CLU_NOL_Lock
  1021.  
  1022.    NAME
  1023.    CLU_NOL_Lock -- Obtain a NOL semaphore (V35)
  1024.  
  1025.    SYNOPSIS
  1026.    CLU_NOL_Lock( nol, exclusive )
  1027.                  A0   D0
  1028.  
  1029.    void CLU_NOL_Lock( NOL, BOOL );
  1030.  
  1031.    FUNCTION
  1032.    Obtains a NOL semaphore.
  1033.  
  1034.    INPUTS
  1035.    nolhandle -- standard nol handle.
  1036.    exclusive -- flags for exclusive access.
  1037.  
  1038.    RESULT
  1039.    None.
  1040.  
  1041.    EXAMPLE
  1042.  
  1043.    NOTES
  1044.  
  1045.    BUGS
  1046.    None known.
  1047.  
  1048.    SEE ALSO
  1049.    CLU_NOL_UnLock(), exec.library/ObtainSemaphore(),
  1050.        exec.library/ObtainSemaphoreShared()
  1051.  
  1052. clutil.library/CLU_NOL_NewA                       clutil.library/CLU_NOL_NewA
  1053.  
  1054.    NAME
  1055.    CLU_NOL_NewA -- Create new Named Object List. (V24)
  1056.    CLU_NOL_New -- Tagcall variant of CLU_NOL_NewA (V24)
  1057.  
  1058.    SYNOPSIS
  1059.    nolhandle = CLU_NOL_NewA( taglist )
  1060.       D0                     A0
  1061.  
  1062.    void * CLU_NOL_NewA( struct TagItem * );
  1063.    void * CLU_NOL_New( tag1, tag2, ... );
  1064.  
  1065.    FUNCTION
  1066.    Create a new, empty NOL handle.
  1067.  
  1068.    Possible Tags:
  1069.  
  1070.    NOLT_ENTRYSIZE, ULONG -- define size of list entries. Defaults
  1071.                             to 0, meaning that the list only contains
  1072.                             labels.
  1073.    NOLT_IGNORECASE, BOOL -- ignore case of labels upon search. Defaults
  1074.                             to FALSE.
  1075.  
  1076.    INPUTS
  1077.    taglist -- Pointer to a TagItem array. See definitions above.
  1078.  
  1079.    RESULT
  1080.    nolhandle -- NULL upon error, otherwise a pointer to a private
  1081.                 data structure used for referencing the NOL.
  1082.  
  1083.    EXAMPLE
  1084.        APTR nolhandle;
  1085.        nolhandle = CLU_NOL_New( NOLT_ENTRYSIZE, sizeof( struct mydata ),
  1086.                                 TAG_DONE );
  1087.  
  1088.    NOTES
  1089.  
  1090.    BUGS
  1091.    none known
  1092.  
  1093.    SEE ALSO
  1094.  
  1095. clutil.library/CLU_NOL_SetEntryName       clutil.library/CLU_NOL_SetEntryName
  1096.  
  1097.    NAME
  1098.    CLU_NOL_SetEntryName -- Set name of a nobjhandle
  1099.  
  1100.    SYNOPSIS
  1101.    success = CLU_NOL_SetEntryName( nobjhandle, name )
  1102.    D0                              A0          A1
  1103.  
  1104.    BOOL CLU_NOL_SetEntryName( NOBJ, STRPTR );
  1105.  
  1106.    FUNCTION
  1107.    Sets the name of the given NOBJ. If a object with the same
  1108.    name already exists on the NOL, this function will return
  1109.    FALSE and set IoErr() to ERROR_OBJECT_EXISTS.
  1110.  
  1111.    INPUTS
  1112.    nobjhandle -- as returned by by CLU_NOL_FindEntry() et al.
  1113.    name -- new name of NOBJ. This is copied to a private
  1114.            memory pool and can be reused afterwards.
  1115.  
  1116.    RESULT
  1117.    success -- TRUE or FALSE. See IoErr() for more error information.
  1118.  
  1119.    EXAMPLE
  1120.  
  1121.    NOTES
  1122.  
  1123.    BUGS
  1124.    none known
  1125.  
  1126.    SEE ALSO
  1127.    CLU_NOL_GetEntryName()
  1128.  
  1129. clutil.library/CLU_NOL_SwapEntries         clutil.library/CLU_NOL_SwapEntries
  1130.  
  1131.    NAME
  1132.    CLU_NOL_SwapEntries -- Swap two NOL entries (V35)
  1133.  
  1134.    SYNOPSIS
  1135.    CLU_NOL_SwapEntries( nobjhandle1, nobjhandle2 )
  1136.                         A0           A1
  1137.  
  1138.    void CLU_NOL_SwapEntries( NOBJ, NOBJ );
  1139.  
  1140.    FUNCTION
  1141.    Swaps the position of the two NOBJs on the NOL.
  1142.  
  1143.    INPUTS
  1144.    nobjhandle1 -- a named object handle.
  1145.    nobjhandle2 -- a named object handle.
  1146.  
  1147.    RESULT
  1148.    None.
  1149.  
  1150.    EXAMPLE
  1151.  
  1152.    NOTES
  1153.    This function will produce an CLU_Alert() if the two
  1154.    NOBJs are not on the same NOL.
  1155.  
  1156.    BUGS
  1157.    None known.
  1158.  
  1159.    SEE ALSO
  1160.  
  1161. clutil.library/CLU_NOL_UnLock                   clutil.library/CLU_NOL_UnLock
  1162.  
  1163.    NAME
  1164.    CLU_NOL_UnLock -- Release a NOL semaphore (V35)
  1165.  
  1166.    SYNOPSIS
  1167.    CLU_NOL_UnLock( nol )
  1168.                    A0
  1169.  
  1170.    void CLU_NOL_UnLock( NOL );
  1171.  
  1172.    FUNCTION
  1173.    Releases a NOL semaphore.
  1174.  
  1175.    INPUTS
  1176.    nolhandle -- standard nol handle.
  1177.  
  1178.    RESULT
  1179.    None.
  1180.  
  1181.    EXAMPLE
  1182.  
  1183.    NOTES
  1184.  
  1185.    BUGS
  1186.    None known.
  1187.  
  1188.    SEE ALSO
  1189.    CLU_NOL_Lock(), exec.library/ReleaseSemaphore()
  1190.  
  1191. clutil.library/CLU_OpenLibraryCode         clutil.library/CLU_OpenLibraryCode
  1192.  
  1193.    NAME
  1194.    CLU_OpenLibraryCode -- open Connectline specific libraries.
  1195.  
  1196.    SYNOPSIS
  1197.    libbase = CLU_OpenLibraryCode( libcode )
  1198.    D0                             D0
  1199.  
  1200.    struct Library * CLU_OpenLibraryCode( int );
  1201.  
  1202.    FUNCTION
  1203.    Opens Connectline specific libraries given by a shorthand
  1204.    integer code. This function knows about library locations
  1205.    and versions, and will put up a requester if a correct
  1206.    library version can't be opened.
  1207.  
  1208.    INPUTS
  1209.    libcode -- library code, see "cl/clutil.h"
  1210.  
  1211.    RESULT
  1212.    libbase -- Library base.
  1213.  
  1214.    EXAMPLE
  1215.        CLBase = CLU_OpenLibraryCode( CLULC_CLBOARD );
  1216.  
  1217.    NOTES
  1218.    You normally don't need to call this function on your own,
  1219.    since the constructors/destructors in "cl.lib" will do
  1220.    this for you.
  1221.  
  1222.    BUGS
  1223.    None known.
  1224.  
  1225.    SEE ALSO
  1226.    CLU_OpenLibrary()
  1227.  
  1228. clutil.library/CLU_OpenTempFile               clutil.library/CLU_OpenTempFile
  1229.  
  1230.    NAME
  1231.    CLU_OpenTempFile -- open temporary file (V27)
  1232.  
  1233.    SYNOPSIS
  1234.    fh = CLU_OpenTempFile( size, namearray )
  1235.    D0                     A0    A1
  1236.  
  1237.    BPTR CLU_OpenTempFile( ULONG, STRPTR );
  1238.  
  1239.    FUNCTION
  1240.    Opens a temporary file and (optionally) returns
  1241.    the name of the file created.
  1242.  
  1243.    INPUTS
  1244.    size -- expected size of the temporary file.
  1245.            May be 0, stating "I don't know".
  1246.  
  1247.    namearray -- pointer to a char array of at least 256
  1248.                 bytes to receive the full path name
  1249.                 of the file opened. May be NULL,
  1250.                 in which case no name is returned.
  1251.    
  1252.    dirlock -- a valid Lock on the directory to examine.
  1253.  
  1254.    RESULT
  1255.    fh -- AmigaDOS filehandle or NULL upon error.
  1256.  
  1257.    EXAMPLE
  1258.        BPTR fh;
  1259.        fh = CLU_OpenTempFile( 8192, NULL );
  1260.        /*...*/
  1261.        CLU_CloseTempFile( fh, TRUE );
  1262.  
  1263.    NOTES
  1264.    The file location depends on the expected size given.
  1265.    Small files might go to the Ram Disk,
  1266.    whereas large files will go to a hard drive location.
  1267.    Setting size to 0 will always cause the "largest"
  1268.    possible location to be selected.
  1269.  
  1270.    BUGS
  1271.    This function is obsolete. Use the appropriate function
  1272.    in cl_prefs.library!
  1273.  
  1274.    SEE ALSO
  1275.    CLU_CloseTempFile()
  1276.  
  1277. clutil.library/CLU_ScanDir                         clutil.library/CLU_ScanDir
  1278.  
  1279.    NAME
  1280.    CLU_ScanDir -- scan a directory and call hook for every entry (V26)
  1281.  
  1282.    SYNOPSIS
  1283.    count = CLU_ScanDir( dirlock, pattern, hookfunc, userdata )
  1284.    D0                   A0       A1       A2        A3
  1285.  
  1286.    int CLU_ScanDir( BPTR, STRPTR, HOOKFUNC, APTR );
  1287.  
  1288.    FUNCTION
  1289.    Scan a directory and call the hook function for every
  1290.    entry found. Optional pattern match.
  1291.  
  1292.    INPUTS
  1293.    dirlock -- a valid Lock on the directory to examine.
  1294.  
  1295.    pattern -- optional match pattern or NULL.
  1296.  
  1297.    hookfunc -- function pointer to your hook function. The
  1298.                hook function is called with a pointer to
  1299.                a FileInfoBlock in A1 and with your userdata
  1300.                pointer in A3. The hookfunc must return
  1301.                an boolean value in D0 meaning FALSE for aborting
  1302.                scan and TRUE to continue.
  1303.  
  1304.    userdata -- optional user data pointer passed to your
  1305.                hook function in A3.
  1306.  
  1307.    RESULT
  1308.    count -- number of matching entries or -1 if an error
  1309.             occured (see IoErr() for more information)
  1310.  
  1311.    EXAMPLE
  1312.  
  1313.  
  1314.    NOTES
  1315.  
  1316.    BUGS
  1317.    none known
  1318.  
  1319.    SEE ALSO
  1320.    CLU_MakeFileList()
  1321.  
  1322. clutil.library/CLU_SkipDot                         clutil.library/CLU_SkipDot
  1323.  
  1324.    NAME
  1325.    CLU_SkipDot -- skip first char if "." (V39)
  1326.  
  1327.    SYNOPSIS
  1328.    newptr = CLU_SkipDot( string )
  1329.      D0                    A0
  1330.  
  1331.    STRPTR CLU_SkipDot( STRPTR );
  1332.  
  1333.    FUNCTION
  1334.    Skips first char if '.'
  1335.  
  1336.    INPUTS
  1337.    string -- Input string pointer.
  1338.  
  1339.    RESULT
  1340.    newptr -- possibly updated string pointer.
  1341.  
  1342.    EXAMPLE
  1343.  
  1344.    NOTES
  1345.  
  1346.    BUGS
  1347.  
  1348.    SEE ALSO
  1349.  
  1350.